Skip to content

docs: document zero-threshold policy fix and improve ledger/policy inline docs#4

Merged
Gsbreddy merged 1 commit into
chore/1.0.1-v1-rollout-readinessfrom
cursor/codebase-documentation-alignment-70a3
May 1, 2026
Merged

docs: document zero-threshold policy fix and improve ledger/policy inline docs#4
Gsbreddy merged 1 commit into
chore/1.0.1-v1-rollout-readinessfrom
cursor/codebase-documentation-alignment-70a3

Conversation

@cursor
Copy link
Copy Markdown

@cursor cursor Bot commented May 1, 2026

Docs added/updated

CHANGELOG.md

Added a ### Fixed entry under Unreleased for the zero-threshold policy sample bug merged in PR #3. The entry explains what broke (falsy or-based fallback treated an explicit 0 like None), what was fixed (is not None guards), and what it enables (a policy can set thresholds to 0 to unconditionally accept any sample size).

src/flightdeck/ledger.py

Added docstrings to three previously undocumented functions:

  • confidence_label — documents the HIGH / MEDIUM / LOW tier logic, explains that a threshold of 0 is valid and means "no minimum required", and notes the empty-window case.
  • evaluate_policy — lists each constraint checked (max_cost_per_run_usd, max_latency_ms, max_error_rate, require_high_diff_confidence) and documents the skip conditions.
  • diff_releases — full Args/Returns/Raises docstring covering: threshold resolution (None → config default, 0 → explicit override), the agent-id invariant for cross-agent diff rejection, how window is used (label only, not a filter), and the returned DiffResult.

src/flightdeck/models.py

Added a class docstring to Policy that documents the two field groups and their distinct semantics:

  • Constraint fields (max_*) — None disables the constraint.
  • Sample threshold fields (min_*) — None defers to workspace config; 0 unconditionally accepts any sample size (the key distinction introduced by PR fix: respect zero policy sample thresholds #3).

schemas/v1/policy.schema.json

Regenerated (via scripts/generate_schemas.py) to include the new Policy docstring as the JSON Schema description field. All 49 tests pass including test_committed_json_schemas_match_models.

Which codepaths these cover

  • flightdeck.ledger.diff_releases — the primary comparison engine (cost, latency, error-rate rollups, confidence labelling, policy evaluation).
  • flightdeck.models.Policy — the on-disk and in-memory policy object consumed by diff_releases and the CLI's release diff / release promote / release rollback commands.

Key knowledge gaps addressed

  1. The None vs 0 threshold contract was implicit in the code and absent from any docs; it is now explicit in both Policy's docstring and diff_releases's docstring.
  2. What confidence_label thresholds actually mean (including the 0-is-valid edge case) was previously only discoverable by reading the implementation.
  3. Which constraints evaluate_policy checks and when it skips them was undocumented.
  4. The bug and its fix are now captured in CHANGELOG.md so future readers understand why is not None is used instead of or.
Open in Web View Automation 

…cstrings

- CHANGELOG.md: add Fixed entry under Unreleased for PR #3 (zero policy
  sample thresholds were silently ignored due to falsy 'or' fallback;
  now uses 'is not None' checks)
- ledger.py: add docstrings to confidence_label, evaluate_policy, and
  diff_releases explaining threshold semantics (None vs 0 vs config default),
  confidence label tiers, constraint fields, and agent-id invariant
- models.py: add Policy class docstring explaining the None/0 distinction
  for min_* threshold fields versus constraint (max_*) fields
- schemas/v1/policy.schema.json: regenerated to pick up Policy docstring

Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>
@Gsbreddy Gsbreddy marked this pull request as ready for review May 1, 2026 23:44
@Gsbreddy Gsbreddy merged commit 2ffab97 into chore/1.0.1-v1-rollout-readiness May 1, 2026
2 checks passed
@Gsbreddy Gsbreddy deleted the cursor/codebase-documentation-alignment-70a3 branch May 1, 2026 23:45
Gsbreddy added a commit that referenced this pull request May 1, 2026
* feat: FlightDeck 1.0.1 package and v1 rollout readiness

Ship the local-first CLI, schemas, tests, and CI. Slim-repo docs link to
canonical flightdeckdev/flightdeck main. OpenTelemetry is optional-only.

Also: pytest basetemp under .tmp/pytest for Windows, Python 3.13–3.14 in CI,
ruff 0.15.12 aligned with ruff-pre-commit, pre-commit-hooks v5, .gitattributes
LF for golden bundle, CHANGELOG 1.0.1 section and empty Unreleased,
RELEASE_NOTES v1.0.1 patch notes, README quickstart_smoke first.

Co-authored-by: Cursor <cursoragent@cursor.com>

* adds pypi fixes

* adds ci fixes

* fix: respect zero policy sample thresholds (#3)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>

* Fix promotion audit sequencing (#5)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>

* docs: document zero-threshold policy fix and improve ledger/policy docstrings (#4)

- CHANGELOG.md: add Fixed entry under Unreleased for PR #3 (zero policy
  sample thresholds were silently ignored due to falsy 'or' fallback;
  now uses 'is not None' checks)
- ledger.py: add docstrings to confidence_label, evaluate_policy, and
  diff_releases explaining threshold semantics (None vs 0 vs config default),
  confidence label tiers, constraint fields, and agent-id invariant
- models.py: add Policy class docstring explaining the None/0 distinction
  for min_* threshold fields versus constraint (max_*) fields
- schemas/v1/policy.schema.json: regenerated to pick up Policy docstring

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>

---------

Co-authored-by: zendaya <zendaya@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>
Co-authored-by: cursor[bot] <206951365+cursor[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants